路径测量（PathMeasure）

字段（Fields）

length

路径跨所有轮廓的总长度。

local function buildPath(path: Path)
    path:reset()
    path:moveTo(Vector.xy(-150, 0))
    path:cubicTo(Vector.xy(-80, -120), Vector.xy(80, 120), Vector.xy(150, 0))
    path:close()
    end

    function init(self: PathMeasureDemo, _context: Context): boolean
    buildPath(self.path)

    local measure = self.path:measure()
    print('length:', measure.length)

    return true
end

isClosed

仅当路径恰好有一个轮廓且该轮廓闭合时返回 true。 具有多个轮廓的路径始终返回 false，即使所有轮廓都闭合。

local function buildPath(path: Path)
    path:reset()
    path:moveTo(Vector.xy(-150, 0))
    path:cubicTo(Vector.xy(-80, -120), Vector.xy(80, 120), Vector.xy(150, 0))
    end

    function init(self: PathMeasureDemo, _context: Context): boolean
    buildPath(self.path)

    local measure = self.path:measure()
    print('isClosed:', measure.isClosed)

    return true
end

方法（Methods）

positionAndTangent

positionAndTangent(distance: number) -> (Vector, Vector)

返回路径上给定距离处的位置和切线向量。 距离会被限制在有效范围 [0, length] 内。返回两个 Vector 值：位置和归一化切线向量。

function draw(self: PathMeasureDemo, renderer: Renderer)
  -- Draw the base path
  renderer:drawPath(self.path, pathPaint)

  local measure = self.path:measure()
  local len = measure.length

  -- positionAndTangent: 放置一个沿路径移动的点
  local distance = (self.elapsed * 0.3 % 1.0) * len
  local pos, _tan = measure:positionAndTangent(distance)

  self.traveler:reset()
  drawDot(self.traveler, pos.x, pos.y, 8)
  renderer:drawPath(self.traveler, travelerPaint)
end

warp

warp(source: Vector) -> Vector

将点映射到路径上。源点的 x 坐标被解释为沿路径的距离， y 坐标用作切线方向的偏移量。返回映射后的位置作为 Vector。

function draw(self: PathMeasureDemo, renderer: Renderer)
  -- Draw the base path
  renderer:drawPath(self.path, pathPaint)

  local measure = self.path:measure()
  local len = measure.length

  -- warp: 使用距离 (x) 和垂直偏移 (y)
  -- 将点网格映射到路径上，然后在每个映射位置绘制一个点
  self.warpPath:reset()
  local cols, rows = 16, 3
  local gap = 20
  for col = 0, cols do
    for row = -rows, rows do
      local srcX = (col / cols) * len
      local srcY = row * gap
      local warped = measure:warp(Vector.xy(srcX, srcY))
      drawDot(self.warpPath, warped.x, warped.y, 3)
    end
  end
  renderer:drawPath(self.warpPath, warpPaint)
end

extract

extract(startDistance: number, endDistance: number, destination: Path, startWithMove: boolean?) -> ()

从 startDistance 到 endDistance 提取路径的子段，并将其追加到目标路径。 距离会被限制在有效范围 [0, length] 内。如果 startWithMove 为 true（默认）， 提取的段以 moveTo 操作开始。如果为 false，则从目标路径中的上一个点继续。

function draw(self: PathMeasureDemo, renderer: Renderer)
  -- Draw the base path
  renderer:drawPath(self.path, pathPaint)

  local measure = self.path:measure()
  local len = measure.length

  -- extract: 动画化一个沿路径移动的高亮窗口
  local windowSize = len * 0.4
  local startD = (self.elapsed * 0.3 % 1.0) * len
  local endD = startD + windowSize
  self.extractedPath:reset()
  if endD <= len then
    measure:extract(startD, endD, self.extractedPath)
  else
    -- 环绕路径末尾
    measure:extract(startD, len, self.extractedPath)
    measure:extract(0, endD - len, self.extractedPath, false)
  end
  renderer:drawPath(self.extractedPath, extractPaint)
end